<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
    <TITLE>Tutorial</TITLE>
    <LINK REL="stylesheet" HREF="../../../../boost.css">
    <LINK REL="stylesheet" HREF="../theme/iostreams.css">
</HEAD>
<BODY>

<!-- Begin Banner -->

    <H1 CLASS="title">Tutorial</H1>
    <HR CLASS="banner">

<!-- End Banner -->

<!-- Begin Nav -->

<DIV CLASS='nav'>
    <A HREF='writing_filters.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/prev.png'></A>
    <A HREF='tutorial.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/up.png'></A>
    <A HREF='shell_comments_filters.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/next.png'></A>
</DIV>

<!-- End Nav -->


<A NAME="filter_usage"></A>
<H2>2.2.2. Filter Usage Examples</H2>

<P>
    Filters are generally used in conjunction with <A HREF="../guide/filtering_streams.html">filtering streams and stream buffers.</A> For example, suppose you have some text which you want to compress, then Base64 encode, then write to a file. If you have appropriate OutputFilters <CODE>compressor</CODE> and <CODE>base64_encoder</CODE>, you can do this as follows:<A CLASS='footnote_ref' NAME='note_1_ref' HREF="#note_1"><SUP>[1]</SUP></A>
</P>

<PRE CLASS="broken_ie">
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/device/file.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/device/file_descriptor.hpp&gt;</SPAN></A>
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/filtering_stream.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/filtering_stream.hpp&gt;</SPAN></A>

<SPAN CLASS='keyword'>namespace</SPAN> io = boost::iostreams;

<SPAN CLASS="keyword">int</SPAN> main()
{   
    io::filtering_ostream out;
    out.push(compressor());
    out.push(base64_encoder());
    out.push(file_sink("my_file.txt"));
    <SPAN CLASS='comment'>// write to out using std::ostream interface</SPAN>
}</PRE>

<P>
    Like all <A HREF="../guide/filtering_streams.html">filtering streams and stream buffers</A>, <CODE>filtering_ostream</CODE> maintains an internal chain of Filters and Devices. (<I>See also</I> <A HREF="../classes/chain.html"><CODE>chain</CODE></A>.) When data is written to this chain, it flows through the components in the order they were pushed. The last component pushed in the above example could be any model of <A HREF="../concepts/sink.html">Sink</A>, including a <CODE>std::ostream</CODE> such as <CODE>std::cout</CODE>.
</P>
    
<P>
    Now suppose you want to recover the original data. If you have appropriate InputFilters <CODE>decompressor</CODE> and <CODE>base64_decoder</CODE>, you can accomplish this as follows:<A CLASS='footnote_ref' NAME='note_2_ref' HREF="#note_2"><SUP>[2]</SUP></A>
</P>

<PRE CLASS="broken_ie">
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/device/file.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/device/file.hpp&gt;</SPAN></A>
<SPAN CLASS='preprocessor'>#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/filtering_stream.hpp"><SPAN CLASS='literal'>&lt;boost/iostreams/filtering_stream.hpp&gt;</SPAN></A>

<SPAN CLASS='keyword'>namespace</SPAN> io = boost::iostreams;

<SPAN CLASS="keyword">int</SPAN> main()
{   
    io::filtering_istream in;
    in.push(decompressor());
    in.push(base64_decoder());
    in.push(file_source("my_file.txt"));
    <SPAN CLASS='comment'>// read from in using std::istream interface</SPAN>
}</PRE>

<P>
    Here you see another use of a filter chain. When data is read from the chain, it flows through the components in <I>reverse</I> order, beginning with the component pushed last. The last component pushed could be any model of <A HREF="../concepts/source.html">Source</A>, including a <CODE>std::istream</CODE> such as <CODE>std::cin</CODE>.
</P>

<HR>

<!-- Begin Footnotes -->

<P>
    <A CLASS='footnote_ref' NAME='note_1' HREF="#note_1_ref"><SUP>[1]</SUP></A>Strictly speaking, it would be better to use a <A HREF="../classes/file_descriptor.html#file_descriptor_sink"><CODE>file_descriptor_sink</CODE></A> instead of a <A HREF="../classes/file.html#file_sink"><CODE>file_sink</CODE></A> here, because <A HREF="../classes/file_descriptor.html#file_descriptor_sink"><CODE>file_descriptor_sink</CODE></A> never performs <A HREF="../guide/code_conversion.html">code conversion</A>.
</P>

<P>
    <A CLASS='footnote_ref' NAME='note_2' HREF="#note_2_ref"><SUP>[2]</SUP></A>Strictly speaking, it would be better to use a <A HREF="../classes/file_descriptor.html#file_descriptor_source"><CODE>file_descriptor_source</CODE></A> instead of a <A HREF="../classes/file.html#file_source"><CODE>file_source</CODE></A> here, because <A HREF="../classes/file_descriptor.html#file_descriptor_source"><CODE>file_descriptor_source</CODE></A> never performs <A HREF="../guide/code_conversion.html">code conversion</A>.
</P>

<!-- Begin Nav -->

<DIV CLASS='nav'>
    <A HREF='writing_filters.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/prev.png'></A>
    <A HREF='tutorial.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/up.png'></A>
    <A HREF='shell_comments_filters.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/next.png'></A>
</DIV>

<!-- End Nav -->

<!-- Begin Footer -->

<HR>


<P CLASS="copyright">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" target="_top">Jonathan Turkanis</a></P>
<P CLASS="copyright"> 
    Use, modification, and distribution are subject to the Boost Software License, Version 2.0. (See accompanying file <A HREF="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)
</P>
<!-- End Footer -->

</BODY>